home *** CD-ROM | disk | FTP | other *** search
/ Adobe Graphics & Publishing SDK 1996 December / Adobe Graphics & Publishing SDK 1996 December.iso / mac / After Effects 3.1 SDK Mac / Examples / Header Files / AE_EffectUI.h < prev    next >
Text File  |  1996-06-19  |  11KB  |  426 lines
  1. /** AE_EffectUI.h
  2.  
  3.     After Effects¬ Custom UI-Related Structure Header File.
  4.  
  5.     Part of the Adobe After Effects 3.1 SDK.
  6.     Copyright (c) 1992-96 Adobe Systems Inc.
  7.     All Rights Reserved.
  8.     
  9.     NOTES
  10.         This file describes the structures and callbacks a plug-in can use
  11.         if it wishes to present a custom user interface.
  12.     
  13.     6/12/96    ba    Updated for After Effects 3.1. 
  14. **/
  15.  
  16. #ifndef _H_AE_EffectUI
  17. #define _H_AE_EffectUI
  18.  
  19.  
  20. #include "AE_Effect.h"
  21.  
  22.  
  23. #if PRAGMA_ALIGN_SUPPORTED
  24. #pragma options align=mac68k
  25. #endif
  26.  
  27.  
  28. EXTERN_C_START
  29.  
  30.  
  31. /** PF_CustomFlags
  32.     
  33.     Kinds of events and actions the custom parameter type might require.
  34.  
  35.  **/
  36. enum {
  37.     PF_CustomEFlag_NONE             = 0,
  38.  
  39.     PF_CustomEFlag_COMP             = 1L << 0,
  40.     PF_CustomEFlag_LAYER            = 1L << 1,
  41.     PF_CustomEFlag_EFFECT            = 1L << 2,
  42.     PF_CustomEFlag_PREVIEW            = 1L << 3
  43. };
  44. typedef long PF_CustomEventFlags;
  45.  
  46.  
  47. /** PF_WindowType
  48.  
  49.     The various AE windows which can have custom UI events.
  50.  
  51. **/
  52. enum {
  53.     PF_Window_NONE = -1,
  54.     PF_Window_COMP,
  55.     PF_Window_LAYER,
  56.     PF_Window_EFFECT,
  57.     PF_Window_PREVIEW
  58. };
  59. typedef long PF_WindowType;
  60.  
  61.  
  62. /** PF_EventType
  63.  
  64.     The event type identifies the kind of UI event that has just taken place.
  65.  
  66. **/
  67. enum {
  68.     PF_Event_NONE = -1,
  69.     PF_Event_NEW_CONTEXT,
  70.     PF_Event_ACTIVATE,
  71.     PF_Event_DO_CLICK,
  72.     PF_Event_DRAG,
  73.     PF_Event_DRAW,
  74.     PF_Event_DEACTIVATE,
  75.     PF_Event_CLOSE_CONTEXT,
  76.     PF_Event_IDLE,
  77.     PF_Event_KEYDOWN,
  78.     
  79.     PF_Event_NUM_EVENTS
  80. };
  81. typedef long PF_EventType;
  82.  
  83.  
  84. /**
  85.  
  86.     Depending on the kind of event, the PF_EventUnion parameter will indicate more 
  87.     information about the event.  Here are the 3 kinds of user events.
  88.  
  89. **/ 
  90. typedef struct {
  91.     unsigned long        when;
  92.     Point                screen_point;
  93.     long                num_clicks;
  94.     long                modifiers;
  95.     long                continue_refcon[4];    /* <> if send_drag is TRUE, set this */
  96.     Boolean                send_drag;            /* << set this from a do_click to get a drag */
  97.     Boolean                last_time;            /* >> set the last time you get a drag */
  98. } PF_DoClickEventInfo;
  99.  
  100. typedef struct {
  101.     Rect        update_rect;        // in window's coordinate system
  102.     long        depth;
  103.     void        *gdeviceH;
  104. } PF_DrawEventInfo;
  105.  
  106. typedef struct {                    // effect should only eat keys when modal!
  107.     unsigned long        when;
  108.     Point                screen_point;
  109.     long                char_code;
  110.     long                key_code;
  111.     long                modifiers;
  112. } PF_KeyDownEvent;
  113.  
  114. typedef union {
  115.     PF_DoClickEventInfo        do_click;    // also drag
  116.     PF_DrawEventInfo        draw;
  117.     PF_KeyDownEvent            key_down;
  118.  
  119.     // add other event types here
  120.         
  121. } PF_EventUnion;
  122.  
  123.  
  124. #define            PF_CONTEXT_MAGIC        0x05ea771e
  125.  
  126. /** PF_Context
  127.  
  128.     The PF_Context structure is returned in the PF_EventExtra structure and is used 
  129.     to identify the context (or window) where the UI event is happening. Most fields
  130.     are read-only.
  131.     
  132. **/
  133. typedef struct {
  134.     unsigned long        magic;
  135.     PF_WindowType        w_type;            // Identifies the AE window context (see above)
  136.     void                *cgrafptr;
  137.     long                reserved_flt;
  138.     long                plugin_state[4];/* A plug-in can store state data specific to a
  139.                                            given context here if it wishes */    
  140. } PF_Context, *PF_ContextPtr, **PF_ContextH;
  141.  
  142.  
  143. /** PF_EventCallBacks
  144.  
  145.     Here are the custom UI callbacks. The functions defined in this block are:
  146.     
  147.     layer_to_comp
  148.         This transforms layer window coordinates to the composition window coordinates.
  149.     
  150.     comp_to_layer
  151.         This transforms composition window coordinates to the layer window coordinates.
  152.     
  153.     get_comp2layer_xform
  154.         This returns the transformation matrix used to convert from the composition window 
  155.         to the layer window. 
  156.  
  157.     get_layer2comp_xform
  158.         This returns the transformation matrix used to convert from the layer window 
  159.         to the composition window.
  160.     
  161.     source_to_frame
  162.         This transforms the source coordinates of the given context to screen coordinates.
  163.     
  164.     frame_to_source
  165.         This transforms screen coordinates to the source coordinates of the given context.
  166.         
  167.     info_draw_color
  168.         This performs the standard color information reporting into the info window which 
  169.         happens as the user moves the mouse over the composition window.
  170.  
  171.     info_draw_text
  172.         This displays the given text in the info window when an object is selected in the 
  173.         comp window.
  174.         
  175.     info_get_port
  176.         This returns the Macintosh grafptr for the info window so you can draw whatever 
  177.         you want into it.
  178.     
  179. **/
  180. typedef struct {
  181.     void        *refcon;            // front-end's refcon
  182.     
  183.     PF_Err        (*layer_to_comp)(
  184.                                 void            *refcon,    /* >> */
  185.                                 PF_ContextH        context,    /* >> */
  186.                                 long            curr_time,    /* >> */
  187.                                 long            time_scale,    /* >> */
  188.                                 PF_FixedPoint    *pt);        /* << */
  189.                                 
  190.     PF_Err        (*comp_to_layer)(
  191.                                 void            *refcon,     /* >> */
  192.                                 PF_ContextH        context,     /* >> */
  193.                                 long            curr_time,     /* >> */
  194.                                 long            time_scale,    /* >> */
  195.                                 PF_FixedPoint    *pt);        /* << */
  196.  
  197.     PF_Err        (*get_comp2layer_xform)(
  198.                                 void            *refcon,     /* >> */
  199.                                 PF_ContextH        context,    /* >> */
  200.                                 long            curr_time,    /* >> */
  201.                                 long            time_scale,    /* >> */
  202.                                 long            *exists,    /* << non-zero if exists */
  203.                                 PF_FloatMatrix    *c2l);        /* << */
  204.                                 
  205.     PF_Err        (*get_layer2comp_xform)(
  206.                                 void            *refcon,    /* >> */
  207.                                 PF_ContextH        context,     /* >> */
  208.                                 long            curr_time,     /* >> */
  209.                                 long            time_scale, /* >> */
  210.                                 PF_FloatMatrix    *l2c);        /* << */
  211.     
  212.     PF_Err        (*source_to_frame)(
  213.                                 void            *refcon,    /* >> */
  214.                                  PF_ContextH    context,    /* >> */
  215.                                  PF_FixedPoint    *pt);        /* << */
  216.                                  
  217.     PF_Err        (*frame_to_source)(
  218.                                 void            *refcon,    /* >> */
  219.                                 PF_ContextH        context,    /* >> */
  220.                                 PF_FixedPoint    *pt);        /* << */
  221.  
  222.     PF_Err        (*info_draw_color)(
  223.                                 void            *refcon,    /* >> */
  224.                                 PF_Pixel        color);        /* >> */
  225.                                 
  226.     PF_Err        (*info_draw_text)(
  227.                                 void            *refcon,    /* >> */
  228.                                 char            *text1,        /* >> Cstring */
  229.                                 char            *text2);    /* >> Cstring */
  230.                                 
  231.     PF_Err        (*info_get_port)(
  232.                                 void            *refcon,            /* >> */
  233.                                 void            **cgrafptr_addr);    /* << */
  234.     
  235. } PF_EventCallbacks, *PF_EventCallbacksPtr;
  236.  
  237.  
  238. enum {
  239.     PF_EA_NONE = 0,
  240.     PF_EA_PARAM_TITLE,
  241.     PF_EA_CONTROL
  242. };
  243. typedef    long PF_EffectArea;
  244.  
  245.  
  246. /** PF_EffectWindowInfo
  247.  
  248.     If an event takes place in an effects window, the following structure will be sent in 
  249.     the PF_EffectWindowInfo field.
  250.  
  251. **/
  252. typedef struct {
  253.     PF_ParamIndex            index;                // identifies which control is being affected
  254.     PF_EffectArea            area;                // indicates the control or control title
  255.     Rect                    current_frame;        // full frame of the current area
  256.     Rect                    param_title_frame;    // full frame of the param title area
  257.      long                    horiz_offset;        // h offset to draw into title
  258. } PF_EffectWindowInfo;
  259.  
  260.  
  261. /** PF_EventOutFlags
  262.  
  263.     Event Output Flags. This currently only contains one value which you can set. Setting it 
  264.     indicates to After Effects that you╒ve handled an event which shouldn╒t be further propagated.
  265.  
  266. **/
  267. enum {
  268.     PF_EO_NONE = 0,
  269.     PF_EO_HANDLED_EVENT        = 1L << 0
  270. };
  271. typedef    long PF_EventOutFlags;
  272.  
  273.  
  274. /** PF_EventInFlags
  275.  
  276.     Event Input Flags. This currently contains only one value, which you should examine before 
  277.     drawing into a comp or layer window. If this flag is set you should avoid drawing
  278.  
  279. **/
  280. enum {
  281.     PF_EI_NONE = 0,
  282.     PF_EI_DONT_DRAW            = 1L << 0        // don't draw controls in comp or layer window
  283. };
  284. typedef    long PF_EventInFlags;
  285.  
  286.  
  287. /** PF_EventExtra
  288.  
  289.     Upon receiving the PF_Cmd_EVENT command selector, the *extra parameter will point to the 
  290.     following structure which describes the UI event.
  291.  
  292. **/
  293. typedef struct {
  294.     PF_ContextH                contextH;            /* >> */
  295.     PF_EventType            e_type;                /* >> */
  296.     PF_EventUnion            u;                    /* >> based on e_type */
  297.     PF_EffectWindowInfo        effect_win;            /* >> only for Effect window do_click and draw */
  298.     PF_EventCallbacks        cbs;                /* >> not for new_context or close_context */
  299.     PF_EventInFlags            evt_in_flags;        /* >> */
  300.     PF_EventOutFlags        evt_out_flags;        /* << */
  301. } PF_EventExtra;
  302.  
  303.  
  304. typedef struct {
  305.     PF_ParamIndex        index;            /* which parameter is this? */
  306.     
  307.     unsigned long        ntrp;            /* 0 .. 0xffffffff, btw left_key and right_key */
  308.     
  309.     PF_ParamDefPtr        left_key;        /* >> */
  310.     PF_ParamDefPtr        right_key;        /* >> */
  311.     
  312.     void                *stream;
  313.     void                *refcon;
  314.     long                time_value;
  315.     unsigned long        time_scale;
  316.     
  317.     PF_ParamDefPtr        result;            /* << already allocated */
  318.         
  319. } PF_NtrpExtra;
  320.  
  321.  
  322. typedef struct {
  323.     long                maj_vers;    
  324.     long                min_vers;
  325.     PF_ParamList        old_params;
  326. } PF_ConvertParamsExtra;
  327.  
  328.  
  329. typedef struct {
  330.     char                name[ PF_MAX_EFFECT_NAME_LEN + 1 ];
  331.     char                category[ PF_MAX_EFFECT_CATEGORY_NAME_LEN + 1 ];
  332.     PF_SpecVersion        spec_version;        /* PF version effect was built with */
  333.     PF_OutFlags            global_outflags;
  334. } PF_PiPLExtra;
  335.  
  336.  
  337. enum {
  338.     PF_UIAlignment_NONE = 0,
  339.     PF_UIAlignment_TOP = 1L << 0,
  340.     PF_UIAlignment_LEFT = 1L << 1,
  341.     PF_UIAlignment_BOTTOM = 1L << 2,
  342.     PF_UIAlignment_RIGHT = 1L << 3
  343. };
  344.  
  345. typedef long PF_UIAlignment;
  346.  
  347. struct _PF_CustomUIInfo {
  348.     
  349.     long                    reserved;
  350.     PF_CustomEventFlags        events;
  351.  
  352.     long                comp_ui_width;
  353.     long                comp_ui_height;
  354.     PF_UIAlignment        comp_ui_alignment;
  355.     
  356.     long                layer_ui_width;
  357.     long                layer_ui_height;
  358.     PF_UIAlignment        layer_ui_alignment;
  359.  
  360.     long                preview_ui_width;
  361.     long                preview_ui_height;
  362.     PF_UIAlignment        preview_ui_alignment;
  363. };
  364.  
  365.  
  366.  
  367. /** ---------- Callback Access Macros ----------
  368.  
  369.     Each of these macros _ASSUMES_ you already have a local named "extra".
  370.     In addition, the macros assume you want to operate on the current context 
  371.     and not some other one.  We know these are heinous assumption, but the 
  372.     template code declares the parameters like that, and by making those 
  373.     assumptions, we can simplify these macros.
  374.     
  375.     The prototypes and comments about each function are given above in
  376.     the PF_EventCallbacks structure definition.
  377.  
  378. **/
  379.  
  380. #define PF_LAYER_TO_COMP(CURR_TIME, TIMESCALE, PT) \
  381.     ((extra)->cbs.layer_to_comp((extra)->cbs.refcon, (extra)->context, \
  382.     (CURR_TIME), (TIME_SCALE), (PT)))
  383.  
  384. #define PF_COMP_TO_LAYER(CURR_TIME, TIMESCALE, PT) \
  385.     ((extra)->cbs.comp_to_layer((extra)->cbs.refcon, (extra)->context, \
  386.     (CURR_TIME), (TIME_SCALE), (PT)))
  387.     
  388. #define PF_GET_COMP2LAYER_XFORM(CURR_TIME, TIMESCALE, EXISTS, C2L) \
  389.     ((extra)->cbs.get_comp2layer_xform((extra)->cbs.refcon, (extra)->context, \
  390.     (CURR_TIME), (TIME_SCALE), (EXISTS), (C2L)))
  391.     
  392. #define PF_GET_LAYER2COMP_XFORM(CURR_TIME, TIMESCALE, L2C) \
  393.     ((extra)->cbs.get_layer2comp_xform((extra)->cbs.refcon, (extra)->context, \
  394.     (CURR_TIME), (TIME_SCALE), (PT)))
  395.     
  396. #define PF_SOURCE_TO_FRAME(PT) \
  397.     ((extra)->cbs.source_to_frame((extra)->cbs.refcon, (extra)->context, \
  398.     (PT)))
  399.     
  400. #define PF_FRAME_TO_SOURCE(PT) \
  401.     ((extra)->cbs.frame_to_source((extra)->cbs.refcon, (extra)->context, \
  402.     (PT)))
  403.     
  404. #define PF_INFO_DRAW_COLOR(COLOR) \
  405.     ((extra)->cbs.info_draw_color((extra)->cbs.refcon, \
  406.     (COLOR)))
  407.     
  408. #define PF_INFO_DRAW_TEXT(TEXT1, TEXT2) \
  409.     ((extra)->cbs.info_draw_text((extra)->cbs.refcon, \
  410.     (TEXT1) (TEXT2)))
  411.     
  412. #define PF_INFO_GET_PORT(CGRAFPTR_ADDR) \
  413.     ((extra)->cbs.info_get_port((extra)->cbs.refcon, \
  414.     (CGRAFPTR_ADDR)))
  415.  
  416.  
  417. EXTERN_C_END
  418.  
  419.  
  420. #if PRAGMA_ALIGN_SUPPORTED
  421. #pragma options align=reset
  422. #endif
  423.  
  424.  
  425. #endif /* _H_AE_EffectUI */
  426.